home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / il_c / ilSharpenKernel.z / ilSharpenKernel
Encoding:
Text File  |  2002-10-03  |  10.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                    IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll - a kernel to do image sharpening (and blurring)
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      ilWatchedObject : ilKernel
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <il/ilCdefs.h>
  16.  
  17.  
  18. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      This class implements a 2D gaussian shaped image sharpening (or blurring
  20.      kernel).  The type of sharpening performed is typically called unsharp
  21.      masking, and results from a weighted subtraction of a blurred version of
  22.      the image from the original.  The filter weights are detemined by the
  23.      formula:
  24.  
  25.                        2    2              2        2
  26.                 -( ( dx + dy ) / (2 * sigma * radius ) )
  27.               e
  28.  
  29.      where:
  30.  
  31.               dx = x distance from center of kernel
  32.               dy = y distance from center of kernel
  33.  
  34.  
  35.      This creates a circularly symmetric, Gaussian shapped kernel.  The filter
  36.      weights are then normalized to produce an output that computes:
  37.  
  38.               (1+sharpness)*I - sharpness*G
  39.  
  40.      where I is the original image G is the orignal image with the gausing
  41.      kernel applied.
  42.  
  43.      Here are some example kernels with the default sharpness factor, 0.5, for
  44.      various radii:
  45.  
  46.                                    -.00002   -.0006   -.0020   -.0006   -.00002
  47.    -.00006   -.0053   -.00006      -.0006    -.0189   -.0581   -.0189   -.0006
  48.    -.0053    1.0215   -.0053       -.0020    -.0581   1.3210   -.0581   -.0020
  49.    -.00006   -.0053   -.00006      -.0006    -.0189   -.0581   -.0189   -.0006
  50.                                    -.00002   -.0013   -.0020   -.0013   -.00002
  51.  
  52.            rrrraaaaddddiiiiuuuussss ==== 1111                               rrrraaaaddddiiiiuuuussss ==== 2222
  53.  
  54.      The default kernel is:
  55.  
  56.                              -.0057   -.0419   -.0057
  57.                              -.0419   1.1903   -.0419
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                    IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  71.  
  72.  
  73.  
  74.                              -.0057   -.0419   -.0057
  75.  
  76.                                    rrrraaaaddddiiiiuuuussss ==== 1111....5555
  77.  
  78.      The kernel weights always sum to one and the clamping attribute is set on
  79.      this kernel so no change in the input range of values will be effected by
  80.      the application of this kernel.
  81.  
  82.  
  83. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
  84.      CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
  85.  
  86.           ilSharpenKernel* ilSharpenKernelCreate(float sharpness=.5,
  87.                                                  float radius.5)
  88.  
  89.      GGGGeeeetttt aaaannnndddd sssseeeetttt sssshhhhaaaarrrrppppeeeennnniiiinnnngggg ppppaaaarrrraaaammmmeeeetttteeeerrrrssss
  90.  
  91.           void ilSharpenKernelSetSharpness(ilSharpenKernel *obj,
  92.                                            float val)
  93.           void ilSharpenKernelSetRadius(ilSharpenKernel *obj, float val)
  94.           void ilSharpenKernelSetSigma(ilSharpenKernel *obj, float val)
  95.           float ilSharpenKernelGetSharpness(ilSharpenKernel *obj)
  96.           float ilSharpenKernelGetRadius(ilSharpenKernel *obj)
  97.           float ilSharpenKernelGetSigma(ilSharpenKernel *obj)
  98.  
  99.  
  100. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  101.      iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll(((())))
  102.  
  103.           ilSharpenKernel* ilSharpenKernelCreate(float sharpness=.5,
  104.                                                  float radius.5)
  105.  
  106.  
  107.           Creates a kernel with the specified _s_h_a_r_p_n_e_s_s and _r_a_d_i_u_s.  The
  108.           sharpness typically ranges from -1 for maximum blur, to 0 for no
  109.           effect, to positive values up to about 10 for various degrees of
  110.           sharpening.  The radius can be any non-negative value.  A radius of
  111.           zero will perform no filtering, while successively larger values
  112.           will filter lower and lower frequencies.  The actual kernel size is
  113.           determined by the formula:
  114.  
  115.               width,height = 1 + 2*(int)radius
  116.  
  117.  
  118.           Thus, a radius of 1.5 will create a 3x3 kernel.
  119.  
  120.      ggggeeeettttRRRRaaaaddddiiiiuuuussss(((())))
  121.  
  122.           float ilSharpenKernelGetRadius(ilSharpenKernel *obj)
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                    IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  137.  
  138.  
  139.  
  140.           This method returns the current radius of the filter as set by the
  141.           constructor or the last call to sssseeeettttRRRRaaaaddddiiiiuuuussss().
  142.  
  143.      ggggeeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss(((())))
  144.  
  145.           float ilSharpenKernelGetSharpness(ilSharpenKernel *obj)
  146.  
  147.  
  148.           This method returns the current sharpness of the filter as set by
  149.           the constructor or the last call to sssseeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss().
  150.  
  151.      ggggeeeettttSSSSiiiiggggmmmmaaaa(((())))
  152.  
  153.           float ilSharpenKernelGetSigma(ilSharpenKernel *obj)
  154.  
  155.  
  156.           This method returns the sigma value used in generating the kernel
  157.           (see the equation above).
  158.  
  159.      sssseeeettttRRRRaaaaddddiiiiuuuussss(((())))
  160.  
  161.           void ilSharpenKernelSetRadius(ilSharpenKernel *obj, float val)
  162.  
  163.  
  164.           This method sets the radius of the kernel to _v_a_l.  The radius can be
  165.           any non-negative value. A radius of zero will perform no filtering,
  166.           while successively larger values will filter lower and lower
  167.           frequencies.  The actual kernel size is determined by the formula:
  168.  
  169.               width,height = 1 + 2*(int)radius
  170.  
  171.  
  172.           If any objects are watching this kernel (see iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt(3))
  173.           then they will be notified that the kernel has changed when this
  174.           method is called.
  175.  
  176.      sssseeeettttSSSShhhhaaaarrrrppppnnnneeeessssssss(((())))
  177.  
  178.           void ilSharpenKernelSetSharpness(ilSharpenKernel *obj,
  179.                                            float val)
  180.  
  181.  
  182.           This method sets the sharpness of the kernel to _v_a_l.  The effect of
  183.           the sharpness value falls into three ranges: positve, between 0 and
  184.           -1, and less than -1.  As the value increases from zero the result
  185.           is a progressively more sharpended image, typically values from 0-10
  186.           are used. Values larger than about 2 produce a fairly extreme
  187.           sharpening effect.  As the value decreases from zero going to -1 the
  188.           result is a progressively more blurry image.  Values less than -1
  189.           produce a weird effect that becomes progressively sharper; this
  190.           range is not normally used.
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. iiiillllSSSShhhhaaaarrrrppppeeeennnnKKKKeeeerrrrnnnneeeellll((((3333))))                    IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  203.  
  204.  
  205.  
  206.           If any objects are watching this kernel (see iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt(3))
  207.           then they will be notified that the kernel has changed when this
  208.           method is called.
  209.  
  210.      sssseeeettttSSSSiiiiggggmmmmaaaa(((())))
  211.  
  212.           void ilSharpenKernelSetSigma(ilSharpenKernel *obj, float val)
  213.  
  214.  
  215.           This method sets the sigma value used in generating the kernel (see
  216.           the equation above).  The default value is 1/3.  The useful range is
  217.           from zero to one.
  218.  
  219. IIIINNNNHHHHEEEERRRRIIIITTTTEEEEDDDD MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
  220.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllKKKKeeeerrrrnnnneeeellll
  221.      ilKernelCalcGain(), ilKernelCopy(), ilKernelGetData(),
  222.      ilKernelGetDataType(), ilKernelGetElement(), ilKernelGetKernelType(),
  223.      ilKernelGetOrigin(), ilKernelGetSize(), ilKernelGetXsize(),
  224.      ilKernelGetYsize(), ilKernelGetZsize(), ilKernelIsClampSet(),
  225.      ilKernelIsEquivalent(), ilKernelScale(), ilKernelSetClamp(),
  226.      ilKernelSetData(), ilKernelSetElement(), ilKernelSetOrigin()
  227.  
  228.    IIIInnnnhhhheeeerrrriiiitttteeeedddd ffffrrrroooommmm iiiillllWWWWaaaattttcccchhhheeeeddddOOOObbbbjjjjeeeecccctttt
  229.      addWatchCallback(), doWatchCallbacks(), removeWatchCallback()
  230.  
  231. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  232.      ilWatchedObject, ilKernel, ilSepShapenKernel
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.